docs: document PRAISONAI_RUN_SYNC_TIMEOUT and shutdown() API (fixes #227)#229
docs: document PRAISONAI_RUN_SYNC_TIMEOUT and shutdown() API (fixes #227)#229MervinPraison wants to merge 1 commit intomainfrom
Conversation
…c_bridge.shutdown() (fixes #227) - Add PRAISONAI_RUN_SYNC_TIMEOUT environment variable documentation to security-environment-variables.mdx - Add graceful shutdown section to gateway.mdx covering praisonai._async_bridge.shutdown() API - Add related environment variables section to cli/env.mdx - Note security parity improvement for PRAISONAI_ALLOW_LOCAL_TOOLS across all entry points Co-authored-by: Mervin Praison <MervinPraison@users.noreply.github.com>
📝 WalkthroughWalkthroughThis PR documents two features across three documentation files: the new Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the documentation to include new environment variables, specifically PRAISONAI_RUN_SYNC_TIMEOUT, and details on graceful shutdown procedures. However, feedback indicates that the implementation for the shutdown function and the timeout variable is missing from the codebase, which will cause errors for users following the documentation. Furthermore, a broken link to the Async Bridge documentation was identified.
| from praisonai._async_bridge import shutdown | ||
|
|
||
| # On SIGTERM / server stop | ||
| shutdown() | ||
| ``` | ||
|
|
||
| `shutdown()` is also registered via `atexit`, so it runs automatically on interpreter exit. Call it manually when you need deterministic cleanup (flushing telemetry exporters, closing async HTTP/DB clients) before the process exits. |
There was a problem hiding this comment.
The shutdown function and its atexit registration are not present in the praisonai/_async_bridge.py file provided in this branch. This will lead to an ImportError when users try to follow the code example, and the described automatic cleanup will not occur. Please ensure the implementation is included in the codebase before documenting it as a public API.
| ### PRAISONAI_RUN_SYNC_TIMEOUT | ||
|
|
||
| Default maximum seconds the wrapper's sync-to-async bridge will wait for a coroutine to complete. | ||
|
|
||
| **Default:** `300` (5 minutes) | ||
|
|
||
| ```bash | ||
| # Tighten for latency-sensitive servers | ||
| export PRAISONAI_RUN_SYNC_TIMEOUT=30 | ||
|
|
||
| # Loosen for long-running batch jobs | ||
| export PRAISONAI_RUN_SYNC_TIMEOUT=3600 | ||
| ``` | ||
|
|
||
| Applies to every `praisonai` CLI entry and wrapper-based server (gateway, a2u, mcp_server, scheduler). The SDK (`praisonaiagents`) uses a separate bridge — see [Async Bridge](/docs/features/async-bridge). |
There was a problem hiding this comment.
The PRAISONAI_RUN_SYNC_TIMEOUT environment variable is not currently implemented in praisonai/_async_bridge.py. The run_sync function does not read this variable, and it defaults to None (infinite wait) rather than the 300 seconds mentioned. Additionally, the link [Async Bridge](/docs/features/async-bridge) appears to be broken as the target file is missing from the documentation structure. Please verify the implementation and the documentation links.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (2)
docs/features/gateway.mdx (1)
340-353: Cross-link to env-var and async-bridge docs per PR objectives.Issue
#227asks that the shutdown section cross-link toPRAISONAI_RUN_SYNC_TIMEOUTand the async-bridge page, and vice versa. Consider adding a short pointer (e.g., a<Card>or inline link to/features/security-environment-variablesand/features/async-bridge) so operators wiring up lifecycle + timeout land on both pages.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/features/gateway.mdx` around lines 340 - 353, Add cross-links in the Graceful Shutdown section referencing the async-bridge docs and the PRAISONAI_RUN_SYNC_TIMEOUT env var so readers can find lifecycle and timeout guidance; update the text around the shutdown() example to include either a small Card or inline links pointing to /features/async-bridge and /features/security-environment-variables and explicitly mention PRAISONAI_RUN_SYNC_TIMEOUT and the shutdown() function so the async-bridge page and the env-var page also link back accordingly.docs/features/security-environment-variables.mdx (1)
107-107: Use evergreen wording for the enforcement note.“Recent PraisonAI versions” will age quickly. Consider stating the current behavior directly, or naming the exact release if that is important for migration.
Suggested wording
-As of recent PraisonAI versions, the `PRAISONAI_ALLOW_LOCAL_TOOLS` gate is enforced consistently across the CLI (`praisonai run`), YAML workflows, and Python (`AgentsGenerator`) entry points. Previously it was only enforced on one path. +The `PRAISONAI_ALLOW_LOCAL_TOOLS` gate is enforced consistently across the CLI (`praisonai run`), YAML workflows, and Python (`AgentsGenerator`) entry points.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/features/security-environment-variables.mdx` at line 107, Replace the time-sensitive phrase "As of recent PraisonAI versions" with evergreen wording that states the current behavior directly; e.g. "The PRAISONAI_ALLOW_LOCAL_TOOLS gate is enforced across the CLI (`praisonai run`), YAML workflows, and the Python AgentsGenerator entry point." Keep the reference to the gate constant PRAISONAI_ALLOW_LOCAL_TOOLS and the entry points (`praisonai run`, YAML workflows, AgentsGenerator) so the note is precise and does not rely on version-relative language.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/cli/env.mdx`:
- Line 45: Update the table row for the environment variable
PRAISONAI_RUN_SYNC_TIMEOUT so its description specifies that the timeout applies
only to the wrapper sync-to-async bridge (not all async operations); replace
"Default timeout for async operations (seconds)" with a concise phrasing such as
"Default timeout for the wrapper sync-to-async bridge (seconds)" so the CLI docs
accurately reflect the PR scope.
In `@docs/features/gateway.mdx`:
- Around line 340-353: The docs reference a non-existent function import
"shutdown" from praisonai._async_bridge; that module only exposes
_ensure_background_loop and run_sync and has no atexit registration, so update
the docs to either remove the entire "Graceful Shutdown" section or replace the
snippet with a correct API call that actually exists (do not import shutdown
from praisonai._async_bridge). If graceful shutdown functionality exists under a
different public symbol, change the import and example to use that real
function; otherwise delete the section to avoid instructing users to import a
missing symbol.
In `@docs/features/security-environment-variables.mdx`:
- Around line 190-204: The docs claim PRAISONAI_RUN_SYNC_TIMEOUT is honored but
the code never reads it; implement support by parsing the
PRAISONAI_RUN_SYNC_TIMEOUT env var (default 300) in the wrapper startup paths
(e.g., code in base.py, a2u_server.py, managed_local.py), pass that timeout
value into calls to run_sync() instead of hardcoding values (update any
run_sync(...) calls to accept a timeout param) and remove or stop referencing
the non‑existent praisonai._async_bridge.shutdown hook (or implement a proper
shutdown in praisonai._async_bridge and call it if you prefer); alternatively,
if you choose not to implement it, update the docs to remove the unsupported
claims and mark the section as planned—refer to PRAISONAI_RUN_SYNC_TIMEOUT,
run_sync, and praisonai._async_bridge in your changes.
---
Nitpick comments:
In `@docs/features/gateway.mdx`:
- Around line 340-353: Add cross-links in the Graceful Shutdown section
referencing the async-bridge docs and the PRAISONAI_RUN_SYNC_TIMEOUT env var so
readers can find lifecycle and timeout guidance; update the text around the
shutdown() example to include either a small Card or inline links pointing to
/features/async-bridge and /features/security-environment-variables and
explicitly mention PRAISONAI_RUN_SYNC_TIMEOUT and the shutdown() function so the
async-bridge page and the env-var page also link back accordingly.
In `@docs/features/security-environment-variables.mdx`:
- Line 107: Replace the time-sensitive phrase "As of recent PraisonAI versions"
with evergreen wording that states the current behavior directly; e.g. "The
PRAISONAI_ALLOW_LOCAL_TOOLS gate is enforced across the CLI (`praisonai run`),
YAML workflows, and the Python AgentsGenerator entry point." Keep the reference
to the gate constant PRAISONAI_ALLOW_LOCAL_TOOLS and the entry points
(`praisonai run`, YAML workflows, AgentsGenerator) so the note is precise and
does not rely on version-relative language.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 9fd9b686-867c-4f56-bdab-dce27275041d
📒 Files selected for processing (3)
docs/cli/env.mdxdocs/features/gateway.mdxdocs/features/security-environment-variables.mdx
| | `PRAISONAI_ALLOW_LOCAL_TOOLS` | Enable local tools.py file loading | | ||
| | `PRAISONAI_ALLOW_JOB_WORKFLOWS` | Enable job workflow execution | | ||
| | `PRAISONAI_BROWSER_ALLOW_REMOTE` | Enable remote browser access | | ||
| | `PRAISONAI_RUN_SYNC_TIMEOUT` | Default timeout for async operations (seconds) | |
There was a problem hiding this comment.
Narrow the timeout description to the wrapper bridge.
Line 45 currently reads like this controls all async operations. The PR objective scopes it to the wrapper sync-to-async bridge, so the CLI table should avoid over-promising.
Suggested wording
-| `PRAISONAI_RUN_SYNC_TIMEOUT` | Default timeout for async operations (seconds) |
+| `PRAISONAI_RUN_SYNC_TIMEOUT` | Default timeout for the wrapper sync-to-async bridge (seconds) |📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| | `PRAISONAI_RUN_SYNC_TIMEOUT` | Default timeout for async operations (seconds) | | |
| | `PRAISONAI_RUN_SYNC_TIMEOUT` | Default timeout for the wrapper sync-to-async bridge (seconds) | |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/cli/env.mdx` at line 45, Update the table row for the environment
variable PRAISONAI_RUN_SYNC_TIMEOUT so its description specifies that the
timeout applies only to the wrapper sync-to-async bridge (not all async
operations); replace "Default timeout for async operations (seconds)" with a
concise phrasing such as "Default timeout for the wrapper sync-to-async bridge
(seconds)" so the CLI docs accurately reflect the PR scope.
| ## Graceful Shutdown | ||
|
|
||
| Long-running servers can stop the wrapper's background async loop explicitly: | ||
|
|
||
| ```python | ||
| from praisonai._async_bridge import shutdown | ||
|
|
||
| # On SIGTERM / server stop | ||
| shutdown() | ||
| ``` | ||
|
|
||
| `shutdown()` is also registered via `atexit`, so it runs automatically on interpreter exit. Call it manually when you need deterministic cleanup (flushing telemetry exporters, closing async HTTP/DB clients) before the process exits. | ||
|
|
||
| --- |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Locate the async bridge module and inspect for shutdown() + atexit registration.
fd -t f '_async_bridge.py'
fd -t f '_async_bridge.py' --exec cat {}
echo "---- symbol search ----"
rg -nP '\b(def\s+shutdown|atexit\.register|__all__)\b' -C2Repository: MervinPraison/PraisonAIDocs
Length of output: 50383
Remove the "Graceful Shutdown" section or correct the API reference.
The code snippet imports from praisonai._async_bridge import shutdown, but the praisonai/_async_bridge.py module contains only _ensure_background_loop() and run_sync() functions. There is no shutdown() function or atexit registration in that module. This import will raise ImportError at runtime. Either remove this section entirely or replace it with a corrected example if graceful shutdown support exists elsewhere in the API.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/features/gateway.mdx` around lines 340 - 353, The docs reference a
non-existent function import "shutdown" from praisonai._async_bridge; that
module only exposes _ensure_background_loop and run_sync and has no atexit
registration, so update the docs to either remove the entire "Graceful Shutdown"
section or replace the snippet with a correct API call that actually exists (do
not import shutdown from praisonai._async_bridge). If graceful shutdown
functionality exists under a different public symbol, change the import and
example to use that real function; otherwise delete the section to avoid
instructing users to import a missing symbol.
| ### PRAISONAI_RUN_SYNC_TIMEOUT | ||
|
|
||
| Default maximum seconds the wrapper's sync-to-async bridge will wait for a coroutine to complete. | ||
|
|
||
| **Default:** `300` (5 minutes) | ||
|
|
||
| ```bash | ||
| # Tighten for latency-sensitive servers | ||
| export PRAISONAI_RUN_SYNC_TIMEOUT=30 | ||
|
|
||
| # Loosen for long-running batch jobs | ||
| export PRAISONAI_RUN_SYNC_TIMEOUT=3600 | ||
| ``` | ||
|
|
||
| Applies to every `praisonai` CLI entry and wrapper-based server (gateway, a2u, mcp_server, scheduler). The SDK (`praisonaiagents`) uses a separate bridge — see [Async Bridge](/docs/features/async-bridge). |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Verify PRAISONAI_RUN_SYNC_TIMEOUT is consumed by wrapper entry points
# and that the public shutdown() hook exists.
set -euo pipefail
echo "Checking timeout env var usage and run_sync call sites..."
rg -n -C3 'PRAISONAI_RUN_SYNC_TIMEOUT|run_sync\s*\(' --glob '!docs/**'
echo
echo "Checking shutdown API definition..."
rg -n -C3 'def\s+shutdown\s*\(' --glob '!docs/**'Repository: MervinPraison/PraisonAIDocs
Length of output: 42789
🏁 Script executed:
# Check the _async_bridge.py implementation for timeout handling and shutdown
cat -n praisonai/_async_bridge.py | head -100Repository: MervinPraison/PraisonAIDocs
Length of output: 2512
🏁 Script executed:
# Search for where PRAISONAI_RUN_SYNC_TIMEOUT might be read/set
rg -n "RUN_SYNC_TIMEOUT|getenv.*timeout|environ.*timeout" --glob '!docs/**'Repository: MervinPraison/PraisonAIDocs
Length of output: 53
🏁 Script executed:
# Search for wrapper entry points (gateway, a2u, mcp_server, scheduler)
fd -e py -type f | xargs rg -l "gateway|a2u_server|mcp_server|scheduler" --glob '!docs/**' | head -5Repository: MervinPraison/PraisonAIDocs
Length of output: 440
🏁 Script executed:
# Check if any wrapper code tries to read PRAISONAI_RUN_SYNC_TIMEOUT or pass timeout to run_sync
rg -n "run_sync\(" praisonai/endpoints/ praisonai/integrations/ --glob '!docs/**' -A2 -B2 | head -80Repository: MervinPraison/PraisonAIDocs
Length of output: 3272
🏁 Script executed:
# Confirm there is no shutdown in _async_bridge
wc -l praisonai/_async_bridge.py
tail -20 praisonai/_async_bridge.pyRepository: MervinPraison/PraisonAIDocs
Length of output: 690
Document PRAISONAI_RUN_SYNC_TIMEOUT environment variable contract accurately or remove unsupported claims.
The documented environment variable is not consumed by the codebase:
- No wrapper (base.py, a2u_server.py, managed_local.py) reads
PRAISONAI_RUN_SYNC_TIMEOUT run_sync()calls in wrappers pass no timeout parameter (except one hardcodedtimeout=120)- The
shutdown()hook does not exist inpraisonai._async_bridgemodule
Either implement support for the environment variable (parse it in wrappers, pass it to run_sync() calls, and set the 300-second default) or update the documentation to reflect the actual behavior: timeouts are passed as explicit parameters only and no shutdown hook exists in _async_bridge.
Suggested documentation revision
### PRAISONAI_RUN_SYNC_TIMEOUT
Default maximum seconds the wrapper's sync-to-async bridge will wait for a coroutine to complete.
+**Type:** float seconds
**Default:** `300` (5 minutes)
+**Recommended range:** use `30`-`300` for interactive servers; use larger values only for known long-running batch workloads.
```bash
# Tighten for latency-sensitive servers
export PRAISONAI_RUN_SYNC_TIMEOUT=30
# Loosen for long-running batch jobs
export PRAISONAI_RUN_SYNC_TIMEOUT=3600
+
+# Restore the default behavior
+unset PRAISONAI_RUN_SYNC_TIMEOUT-Applies to every praisonai CLI entry and wrapper-based server (gateway, a2u, mcp_server, scheduler). The SDK (praisonaiagents) uses a separate bridge — see Async Bridge.
+Applies to praisonai CLI entries and wrapper-based servers (gateway, a2u, mcp_server, scheduler). The SDK (praisonaiagents) uses a separate bridge — see Async Bridge.
Alternatively, if this variable is not yet implemented, consider marking the section as "Planned" or deferring documentation until the feature is complete.
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
Verify each finding against the current code and only fix it if needed.
In @docs/features/security-environment-variables.mdx around lines 190 - 204, The
docs claim PRAISONAI_RUN_SYNC_TIMEOUT is honored but the code never reads it;
implement support by parsing the PRAISONAI_RUN_SYNC_TIMEOUT env var (default
300) in the wrapper startup paths (e.g., code in base.py, a2u_server.py,
managed_local.py), pass that timeout value into calls to run_sync() instead of
hardcoding values (update any run_sync(...) calls to accept a timeout param) and
remove or stop referencing the non‑existent praisonai._async_bridge.shutdown
hook (or implement a proper shutdown in praisonai._async_bridge and call it if
you prefer); alternatively, if you choose not to implement it, update the docs
to remove the unsupported claims and mark the section as planned—refer to
PRAISONAI_RUN_SYNC_TIMEOUT, run_sync, and praisonai._async_bridge in your
changes.
</details>
<!-- fingerprinting:phantom:poseidon:ibis -->
<!-- This is an auto-generated comment by CodeRabbit -->
Summary
Document the new user-facing features from PraisonAI PR #1505:
PRAISONAI_RUN_SYNC_TIMEOUT- controls default timeout for wrapper's sync-to-async bridge (defaults to 300 seconds)praisonai._async_bridge.shutdown()- enables graceful shutdown of background async loop for long-running serversPRAISONAI_ALLOW_LOCAL_TOOLSis now consistently enforced across all entry pointsChanges
PRAISONAI_RUN_SYNC_TIMEOUTsection with usage examples and security parity note forPRAISONAI_ALLOW_LOCAL_TOOLSshutdown()APITest Plan
Fixes #227
🤖 Generated with Claude Code
Summary by CodeRabbit